github-base

github-base

JavaScript wrapper that greatly simplifies working with GitHub's API.

Install

Install with npm:

$ npm install --save github-base

Heads up!

This lib was completely refactored in v0.2.0. Please see the API documentation for more details.

About

This library provides the necessary methods for creating your own GitHub API library or more specific functionality built on top of these methods.

• .request: the base handler all of the GitHub API VERBS: GET, PUT, POST, DELETE, PATCH
• .get: proxy for request('GET', path, data, cb)
• .paged: makes repeat .get() requests until the page of data has been retrieved.
• .del: proxy for request('DEL', path, data, cb)
• .patch: proxy for request('PATCH', path, data, cb)
• .post: proxy for request('POST', path, data, cb)
• .put: proxy for request('PUT', path, data, cb)

Usage

var GitHub = require('github-base');
var github = new GitHub({
  username: YOUR_USERNAME,
  password: YOUR_PASSWORD,
});

// or 
var github = new GitHub({
  token: YOUR_TOKEN
});

// or 
var github = new GitHub({
  bearer: YOUR_JWT
});

Why another "GitHub API" lib?

Every other GitHub API library I found either had a huge dependency tree, tries to be everything to everyone, was too bloated with boilerplace code, was too opinionated or not maintained.

API

GitHub

Create an instance of GitHub with the given options.

Params

• options {Object}

Example

var GitHub = require('github-base');
var github = new GitHub(options);

.request

Uses simple-get to make a single request to the GitHub API, based on the provided settings. Supports any of the GitHub API VERBs:

• GET
• PUT
• POST
• DELETE
• PATCH

Params

• method {String}: The http VERB to use
• url {String}: GitHub API URL to use.
• options {Options}: Request options.
• cb {Function}

Example

//example..request
github.request('GET', '/user/orgs', function (err, res) {
  //=> array of orgs
});

.get

Makes a single GET request to the GitHub API based on the provided settings.

Params

• path {String}: path to append to the GitHub API URL.
• options {Options}: Request options.
• cb {Function}

Example

// get orgs for the authenticated user
github.get('/user/orgs', function (err, res) {
  //=> array of orgs
});

// get gists for the authenticated user
github.get('/gists', function (err, res) {
  //=> array of gists
});

.paged

Performs a request using simple-get, and then if necessary requests additional paged content based on the response. Data from all pages are concatenated together and buffered until the last page of data has been retrieved.

Params

• path {String}: path to append to the GitHub API URL.
• cb {Function}

Example

// get all repos for the authenticated user
var url = '/user/repos?type=all&per_page=1000&sort=updated';
github.paged(url, function(err, res) {
  console.log(res);
});

.del

Makes a single DELETE request to the GitHub API based on the provided settings.

Params

• path {String}: path to append to the GitHub API URL.
• options {Options}: Request options.
• cb {Function}

Example

// un-follow someone
github.del('/user/following/someoneelse', function(err, res) {
  console.log(res);
});

.patch

Makes a single PATCH request to the GitHub API based on the provided settings.

Params

• path {String}: path to append to the GitHub API URL.
• options {Options}: Request options.
• cb {Function}

Example

// update a gist
var fs = require('fs');
var opts = {files: {'readme.md': { content: '# My Readme...' }}};
github.patch('/gists/bd139161a425896f35f8', opts, function(err, res) {
  console.log(err, res);
});

.post

Makes a single POST request to the GitHub API based on the provided settings.

Params

• path {String}: path to append to the GitHub API URL.
• options {Options}: Request options.
• cb {Function}

Example

// create a new repo
var opts = { name:  'new-repo-name' };
github.post('/user/repos', opts, function(err, res) {
  console.log(res);
});

.put

Makes a single PUT request to the GitHub API based on the provided settings.

Params

• path {String}: path to append to the GitHub API URL.
• options {Options}: Request options.
• cb {Function}

Example

// follow someone
github.put('/user/following/jonschlinkert', function(err, res) {
  console.log(res);
});

#extend

Static method for inheriting the prototype and static methods of the Base class. This method greatly simplifies the process of creating inheritance-based applications. See static-extend for more details.

Params

• Ctor {Function}: constructor to extend

Example

var GitHub = require('github-base');
function MyApp() {
  GitHub.call(this);
}
GitHub.extend(MyApp);

About

Related projects

• ask-for-github-auth: Prompt a user for their github authentication credentials and save the results. | homepage
• gists: Methods for working with the GitHub Gist API. Node.js/JavaScript | homepage
• github-contributors: Generate a markdown or JSON list of contributors for a project using the GitHub API. | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Contributors

Commits	Contributor
31	jonschlinkert
7	tunnckoCore
6	doowb

Building docs

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

To generate the readme, run the following command:

$ npm install -g verbose/verb#dev verb-generate-readme && verb

Running tests

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

$ npm install && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2017, Jon Schlinkert. Released under the MIT License.

This file was generated by verb-generate-readme, v0.4.3, on April 06, 2017.

Changelog

[0.5.4] - 2017-04-19

• ensure simple-get does not try to parse json